receiver/httpcheck: add structured validation result metrics by VenuEmmadi · Pull Request #48443 · open-telemetry/opentelemetry-collector-contrib

VenuEmmadi · 2026-05-17T15:18:38Z

Description

Adds structured response validation metrics to the HTTP Check Receiver.

Problem: Previously, httpcheck.validation.passed and httpcheck.validation.failed only exposed aggregated counts per validation type, making it difficult to identify which specific validation rule passed or failed when multiple validations were configured for the same endpoint.

Solution: This change introduces a new metric, httpcheck.validation.result, which emits one datapoint per validation rule.

The new metric emits one datapoint per validation rule with the following structured attributes:

Attribute	Description	Example
`validation.type`	Type of validation performed	`json_path`, `contains`, `regex`, `size`
`validation.path`	The expression being evaluated	`system_3`, `healthy`, `^ok$`
`validation.expected`	Expected value (when `equals` specified)	`true`, `ok`, `200`
`validation.result`	Pass/fail result of the validation	`passed`, `failed`

Example Output:

httpcheck.validation.result{
  validation.type="json_path",
  validation.path="system_3",
  validation.expected="true",
  validation.result="failed"
} = 1

This enables users to:

Identify exactly which validation failed
Query validations by JSON path or validation expression
Monitor multiple validations from a single HTTP request
Avoid configuring multiple duplicate receivers for the same endpoint

Why this matters: Without this change, a user with the following API response:

{"system_1": true, "system_2": true, "system_3": false}

and multiple validations would only see aggregated validation counts, without visibility into which specific validation failed. The new structured metric makes each validation independently observable.

Backward compatibility: The following legacy metrics continue to work unchanged as aggregate metrics that expose counts grouped by validation type:

httpcheck.validation.passed
httpcheck.validation.failed

Link to tracking issue

Fixes #44662

Testing

Added unit tests covering:

Structured validation result metrics
JSON path validation attributes
Passed and failed validation scenarios
Backward compatibility for legacy metrics
Multiple validation types:
- json_path
- contains
- regex
- size

Verified:

One datapoint is emitted per validation rule
validation.path correctly identifies the evaluated validation
validation.result correctly reports passed/failed state
Legacy metrics continue emitting aggregated counts by validation type

Documentation

Updated receiver/httpcheckreceiver/README.md with:

Documentation for the new httpcheck.validation.result metric
Structured attribute descriptions
Example metric outputs
Multiple JSON path validation examples
Backward compatibility notes for legacy metrics
Updated validation configuration examples
Clarification for gjson path syntax usage

- Add validation.target attribute to httpcheck.validation.passed and httpcheck.validation.failed metrics - Emit one datapoint per validation instead of aggregated counts - Update documentation and tests

- Add new httpcheck.validation.result metric with structured attributes: - validation.type: Type of validation (json_path, contains, regex, size, not_contains) - validation.path: The expression being evaluated - validation.expected: Expected value (when equals specified) - validation.result: Passed or failed result - Keep old httpcheck.validation.passed/failed metrics for backward compatibility - Fix per-type counting for old metrics (no longer hardcoded to json_path) - Emit one data point per validation for structured metric - Add comprehensive test TestValidationResultStructuredAttributes - Support mixed validation types (json_path, contains, regex, size) - Update README with examples and documentation

thompson-tomo · 2026-05-18T04:10:25Z

      monotonic: false
    unit: "{validation}"
    attributes: [http.url, validation.type]
+  httpcheck.validation.result:


Suggested change

httpcheck.validation.result:

httpcheck.validation.outcome:

Thanks for the suggestion! I'd prefer to keep httpcheck.validation.result as the metric name since result is a common term in OpenTelemetry and matches existing patterns. outcome is less commonly used for validation metrics across OTel components.

The problem is you end with an attribute in a metric with the same name which is confusing. This pattern of using outcome for the metric and result is used in semantic conventions. And In fact there is a rule for ensuring they differ: https://github.com/instrumentation-score/spec/blob/main/rules/MET-006.md

thompson-tomo · 2026-05-18T04:11:23Z

+      aggregation_temporality: cumulative
+      monotonic: false
+    unit: "{validation}"
+    attributes: [http.url, validation.type, validation.path, validation.expected, validation.result]


Suggested change

attributes: [http.url, validation.type, validation.path, validation.expected, validation.result]

attributes: [http.url, httpcheck.validation.type, httpcheck.validation.path, httpcheck. validation.expected, httpcheck.validation.result]

Lets Keep current names. OTel conventions typically use short, scoped names. validation.type is clear within httpcheck context.

Actually that is not the case, the naming guidance is https://opentelemetry.io/docs/specs/semconv/general/naming/#general-naming-considerations.

Key thing is:

Be precise. Attribute, event, metric, and other names should be descriptive and unambiguous.

Note If you see an attribute validation.type you have no idea what the scope is just by looking at it hence why new attribute names are being scoped under the appropriate namespace.

Further along in that doc it mentions:

The name is specific to your application that will be used internally only. If you already have an internal company process that helps you to ensure no name clashes happen then feel free to follow it. Otherwise it is recommended to prefix the attribute name by your application name, provided that the application name is reasonably unique within your organization (e.g. myuniquemapapp.longitude is likely fine). Make sure the application name does not clash with an existing semantic convention namespace.

Which is why attributes are prefixed.

thompson-tomo · 2026-05-18T04:28:01Z

+  httpcheck.validation.result:
+    description: Result of a response validation (1 for each validation, with result attribute).
+    enabled: false
+    stability: development
+    sum:
+      value_type: int
+      aggregation_temporality: cumulative
+      monotonic: false
+    unit: "{validation}"
+    attributes: [http.url, validation.type, validation.path, validation.expected, validation.result]


I am wondering if we should remove validation.path & validation.expected from a metric due to cardinality & instead complement the metric with an event httpcheck.validation.failure. This event would emit that lower level detail and can add things like error.message.

Lets Keep as is. Cardinality is safe (static config values). Events would make debugging harder for users.

How so, adding an event would make things easier to debug as the event can contain additional attributes ie error.message?

The cardinality is higher as you end up with data points for every combination of attributes. The key thing the metric is for reporting status of the check of a http.url.

@thompson-tomo could you please review now.

Co-authored-by: James Thompson <thompson.tomo@outlook.com>

- Add new httpcheck.validation.outcome metric with namespaced attributes - Remove deprecated passed/failed metrics (breaking change, alpha component) - Remove validation.expected attribute (cardinality risk) - One datapoint per validation rule - Add comprehensive tests and documentation

thompson-tomo · 2026-05-19T08:28:30Z

    requirement_level: recommended
-  network.transport:
-    description: OSI transport layer or inter-process communication method.
+  httpcheck.validation.outcome:


Suggested change

httpcheck.validation.outcome:

httpcheck.validation.result:

Attribute should differ to metric name.

thompson-tomo · 2026-05-19T08:28:59Z

      monotonic: false
    unit: "{validation}"
-    attributes: [http.url, validation.type]
+    attributes: [http.url, httpcheck.validation.type, httpcheck.validation.target, httpcheck.validation.outcome]


Suggested change

attributes: [http.url, httpcheck.validation.type, httpcheck.validation.target, httpcheck.validation.outcome]

attributes: [http.url, httpcheck.validation.type, httpcheck.validation.target, httpcheck.validation.result]

thompson-tomo · 2026-05-19T08:38:07Z

-  httpcheck.validation.failed:
-    description: Number of response validations that failed.
-    enabled: false
-    stability: development
-    sum:
-      value_type: int
-      aggregation_temporality: cumulative
-      monotonic: false
-    unit: "{validation}"
-    attributes: [http.url, validation.type]
-  httpcheck.validation.passed:
-    description: Number of response validations that passed.


Shouldn't this remain for backwards compatibility?

VenuEmmadi added 2 commits May 16, 2026 09:44

Add validation.target attribute to validation metrics

3a43526

- Add validation.target attribute to httpcheck.validation.passed and httpcheck.validation.failed metrics - Emit one datapoint per validation instead of aggregated counts - Update documentation and tests

VenuEmmadi requested a review from a team as a code owner May 17, 2026 15:18

VenuEmmadi requested a review from codeboten May 17, 2026 15:18

github-actions Bot assigned fatsheep9146 May 17, 2026

github-actions Bot added the receiver/httpcheck HTTP Check receiver label May 17, 2026

VenuEmmadi force-pushed the feature/add-validation-target-attribute branch from 218e063 to 57f506c Compare May 17, 2026 15:31

VenuEmmadi force-pushed the feature/add-validation-target-attribute branch from 57f506c to 5ad48a6 Compare May 17, 2026 15:38

VenuEmmadi added 3 commits May 17, 2026 15:57

Add structured validation result metrics to httpcheck receiver

abce64e

Add structured validation result metrics for httpcheckreceiver

c4ab1bc

fix: regenerate code and fix import ordering

0d328f5

thompson-tomo reviewed May 18, 2026

View reviewed changes

VenuEmmadi and others added 2 commits May 18, 2026 11:52

Update .chloggen/httpcheck-validation-result-metric.yaml

4f9302e

Co-authored-by: James Thompson <thompson.tomo@outlook.com>

fix: rename validation.path to validation.expression

19ee5b3

VenuEmmadi requested a review from thompson-tomo May 18, 2026 06:51

VenuEmmadi and others added 5 commits May 18, 2026 07:03

fix: format imports in generated_package_test.go

1133ff2

Merge branch 'main' into feature/add-validation-target-attribute

70cf842

chore: fix imports and regenerate code

314a46f

Merge branch 'main' into feature/add-validation-target-attribute

7ec87b6

thompson-tomo reviewed May 19, 2026

View reviewed changes

	attributes: [http.url, validation.type, validation.path, validation.expected, validation.result]
	attributes: [http.url, httpcheck.validation.type, httpcheck.validation.path, httpcheck. validation.expected, httpcheck.validation.result]

Conversation

VenuEmmadi commented May 17, 2026

Description

Link to tracking issue

Testing

Documentation

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants